Markdown 语法演示

这份文档逐条演示本站实际支持的 Markdown 写法。每一节都给出源码与渲染结果，可直接对照。

1. 标题

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题

渲染效果：

一级标题

二级标题

三级标题

四级标题

五级标题

标题会自动出现在右侧目录里。目录只收二、三级标题——更深会让目录比正文还长。

1.1 自定义标题 ID

站点开了 headingAttributes，可以给标题指定 id：

## 带自定义 ID 的标题 { #my-custom-id }

效果：

带自定义 ID 的标题

链接到它：点我

2. 段落与换行

这是第一段。

空行之后是第二段。

同一段落里的换行不会保留（HTML 折叠换行）。想强制换行，行尾加两个空格，或者用 <br>。

3. 强调与删除线

*斜体*　**粗体**　***粗斜体***　~~删除线~~

效果：斜体　粗体　粗斜体　删除线

3.1 文字高亮

用 == 包住要突出的文字（与 Obsidian 的写法一致）：

==这是高亮的文字==

效果：这是普通文字，这是高亮的文字，这里又回到普通。

高亮里可以放行内标记，粗体、代码、链接都能正常工作：

==含 **粗体** 的高亮==
==含 `行内代码` 的高亮==
==含 [链接](https://astro.build) 的高亮==

效果：

• 含 粗体 的高亮
• 含 行内代码 的高亮
• 含 链接 的高亮

同一行可以有多个高亮：第一段 中间隔开 第二段，各自独立。

表格、标题、列表、引用块里同样生效：

4. 列表

4.1 无序列表

- 第一项
- 第二项
  - 嵌套项（两空格缩进）
    - 再嵌套一级
- 第三项

效果：

• 第一项
• 第二项
  • 嵌套项（两空格缩进）
    • 再嵌套一级
• 第三项

4.2 有序列表

1. 甲
2. 乙
3. 丙

效果：

1. 甲
2. 乙
3. 丙

4.3 任务列表

- [x] 已完成的事
- [ ] 还没做的事

效果：

• 已完成的事
• 还没做的事

5. 引用块

> 这是一段引用。
> 第二行在同一引用内。

效果：

这是一段引用。
第二行在同一引用内。

6. 提示框（Obsidian callout）

本站保留了 Obsidian 的 callout 语法，并映射到报告体的强调框。

> [!note] 标题
> 正文内容

> [!warning] 注意
> 这里是警告

效果：

支持的类型（映射关系）：

callout 内可以放多种内容：

7. 表格

标准 GFM 表格：

| 语法 | 写法 | 说明 |
| --- | --- | --- |
| 粗体 | `**文字**` | 两侧加星号 |
| 删除线 | `~~文字~~` | 两侧加波浪号 |

效果：

对齐方式（冒号位置决定）：

| 左对齐 | 居中 | 右对齐 |
| :--- | :---: | ---: |
| 内容 | 内容 | 内容 |

8. 链接

[站内链接](/archives/)
[带标题的链接](/tags/ "跳到标签页")
<https://example.com>
https://example.com

效果：

站内链接
带标题的链接
https://example.com
https://example.com

裸 URL 会自动转成链接（GFM 特性）。

9. 图片

![替代文字](/attachments/Markdown%20%E8%AF%AD%E6%B3%95%E6%BC%94%E7%A4%BA/%E7%A4%BA%E4%BE%8B%E5%9B%BE%E7%89%87.jpg)

效果（点击可放大）：

9.1 路径怎么写

图片必须用以 / 开头的绝对路径，指向 public/attachments/ 下的文件。

中文与空格要 URL 编码。用 encodeURI 的规则：

例如 /attachments/Excel 笔记/示例图片.jpg 要写成：

/attachments/Excel%20%E7%AC%94%E8%AE%B0/%E7%A4%BA%E4%BE%8B%E5%9B%BE%E7%89%87.jpg

9.2 徽章行

技术栈徽章（shields.io）放在同一段里会自动排成一行——本站为此专门写了 CSS 判断，段落里全是矮徽章时切换成 flex 布局：

10. 代码

10.1 行内代码

用一对反引号：

这是 `inline code`，还有 ``带反引号的 `代码` ``。

效果：这是 inline code，还有 带反引号的 `代码` 。

10.2 代码块（带语言）

```python
def hello(name: str) -> str:
    return f"Hello, {name}"
```

效果：

def hello(name: str) -> str:
    return f"Hello, {name}"

工具条上会显示语言标签和行数，右侧有复制按钮。

10.3 代码块（不带语言）

```
这里是纯文本输出
```

效果：

这里是纯文本输出

不带语言时渲染成「输出框」样式：没有工具条，左侧有主题色竖线——用来展示终端输出、报错信息这类内容，不会被误读成需要输入的命令。

10.4 长代码自动折叠

超过 10 行的代码块会默认折叠，只显示前 10 行，底部渐隐并给一个「展开其余 N 行」按钮：

SELECT
    o.order_id,
    o.customer_id,
    c.customer_name,
    o.order_date,
    o.total_amount,
    SUM(o.total_amount) OVER (
        PARTITION BY o.customer_id
        ORDER BY o.order_date
        ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
    ) AS running_total
FROM orders o
JOIN customers c ON c.customer_id = o.customer_id
WHERE o.order_date >= '2026-01-01'
  AND o.status = 'completed'
ORDER BY o.customer_id, o.order_date;

-- 结果约 12 行，超过阈值因此被折叠
SELECT COUNT(*) AS total_rows FROM (
    SELECT DISTINCT customer_id FROM orders
) AS t;

行数写在 theme.css 的 :root { --code-collapse-lines } 里，改一处同时影响「是否折叠」和「裁切高度」。

10.5 常用语言标签

标签不区分大小写，但建议统一小写（sql 而非 SQL），Shiki 的语言 id 全是小写：

11. 数学公式

开启 math feature 后，行内用 $...$，独立成行的用 $$...$$。

11.1 行内公式

勾股定理：$a^2 + b^2 = c^2$，欧拉恒等式：$e^{i\pi} + 1 = 0$。

效果：

勾股定理：$a^2 + b^2 = c^2$，欧拉恒等式：$e^{i\pi} + 1 = 0$。

11.2 独立公式

$$
\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}
$$

效果：

$$\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}$$

11.3 常用写法

行内：$a_i + b_i = c_i$　分数：$\frac{a}{b}$　根号：$\sqrt{x}$

上下标：$x^{n+1}$、$x_{i,j}$

运算符：$\sum_{i=1}^{n} x_i$、$\prod_{i=1}^{n} x_i$、$\lim_{n \to \infty}$

关系：$\leq$ $\geq$ $\neq$ $\approx$ $\equiv$

集合：$A \cup B$、$A \cap B$、$\emptyset$、$x \in A$

逻辑：$\forall$ $\exists$ $\neg$ $\land$ $\lor$ $\Rightarrow$

矩阵：$\begin{pmatrix} a & b \\ c & d \end{pmatrix}$

\begin{vmatrix} a & b \\ c & d \end{vmatrix}

效果：

行内：$a_i + b_i = c_i$　分数：$\frac{a}{b}$　根号：$\sqrt{x}$

上下标：$x^{n+1}$、$x_{i,j}$

运算符：$\sum_{i=1}^{n} x_i$、$\prod_{i=1}^{n} x_i$、$\lim_{n \to \infty}$

关系：$\leq$ $\geq$ $\neq$ $\approx$ $\equiv$

集合：$A \cup B$、$A \cap B$、$\emptyset$、$x \in A$

逻辑：$\forall$ $\exists$ $\neg$ $\land$ $\lor$ $\Rightarrow$

矩阵：$\begin{pmatrix} a & b \\ c & d \end{pmatrix}$

$\begin{vmatrix} a & b \\ c & d \end{vmatrix}$

12. 脚注

这是带脚注的句子[^1]，还有一个[^longnote]。

[^1]: 脚注内容，支持 **粗体** 和 `代码`。
[^longnote]: 脚注也可以写很长，一样会排在文末。

效果：

这是带脚注的句子¹，还有一个²。

13. 分隔线

---

效果：

14. 特殊字符与转义

\*这样不会变斜体\*
\# 这样不会变标题
\- 这样不会变列表

效果：

*这样不会变斜体*
# 这样不会变标题
- 这样不会变列表

HTML 实体也可用：© → ©，& → &，< → <

15. 不生效的写法

这些看起来是 Markdown、但在本站不生效，写的时候避开：

需要其中某项的话，在 astro.config.mjs 的 features 里打开对应开关即可。

16. 一份速查